musicbeefandomcom-20200215-history
Tutorial: Creating A Simple Plugin
This article has been created to help show people who are interested in creating a plugin for MusicBee the basic steps to begin. The article will primarily focus on the C# language but should be relatively similar for VB.NET. The screenshots are of Visual Studio 2013 Express unless otherwise stated. This article is a work in progress. All that is required is some basic programming skills, even if you're still learning creating a plugin is a great way of creating working applications that have a meaning! Starting Steps Required Downloads The follow downloads are required for this *The latest version of Visual Studio *The latest API *The latest version of MusicBee (it's recommended you work with a new portable installation rather than your main MusicBee installation, to be safe) Opening the example project For this tutorial, we will be modifying the example project included with the API. This example project contains all the basic methods required to create a plugin for MusicBee. For your own plugins, you should rename the files called TestCSharpDll.cs, etc. Setting up Visual Studio to work with MusicBee For this tutorial we will be creating a plugin that displays a simple form and on the click of a button - interactions with MusicBee will occur. Linking the plugin with MusicBee The name of the plugin must follow the pattern "mb_ExamplePlugin.dll" - without it, MusicBee won't recognise it. Because of this pattern, we must setup Visual Studio to run post-build events - these are used so that we can debug & use visual studio whilst still developing our plugin. (In Visual Studio 2019, this Build Events are found in Project > Properties > Application > Assembly name, at least for C#.) # To begin with, lets add a name & description about our plugin - so we can recognise it in MusicBee. Open the file "TestCSharpDll.cs". On the variables assignments for Name Description and author add the values you want too. # Now, we need to add MusicBee.exe to the project - this will be the process the plugin will be debug in. Click "File > Add > Existing Project". Browse to where MusicBee is installed and double click "MusicBee.exe" 3. In the solution explorer, right click on "MusicBee" and click on "Set as Startup Project" Adding the Build Event Arguments We are now going to add the post-build events. This means that when we want to run the project - it will copy the created files into the Plugins folder for us. This will save time, as we won't need to copy the files manually, only need to press the 'Start' button. The code is as follows copy /Y "$(TargetDir)\*.*" "C:\Program Files (x86)\MusicBee\Plugins\" This command means copy all files in the /bin/debug to the Plugin folder of MusicBee (change the path if you need too).' The speech marks are required'. The /y flag means to overwrite without confirmation. (In Visual Studio 2019, this is also found in Project > Properties. If you're using the VB version, you may have to use Solution Explorer to find it.) Running the Plugin Now that we have MusicBee as the startup application and the build events set. We can easily run the plugin on MusicBee with a single button. In order for this to work MusicBee must be closed. # Rebuild the solution files. On the toolbar of Visual Studio. Select "Build > Rebuild Solution". # Now start debugging the project. Press F5, or on the toolbar Select "Debug > Start With Debugging" Note, if MusicBee doesn't start or an error occurs saying the files cannot be copied. Please double check you have closed MusicBee (more than one instance of MusicBee isn't possible). It may also be possible that Visual Studio needs administrative privileges to be able to write in the plugin folder. To allow this, start Visual Studio as administrator by right clicking on its icon and choosing "Run as administrator". (A workaround, and probably a good idea in general, is to test your plugin with a separate portable installation of MB. That way if you break something, it doesn't mess up your main settings and library.) Check the Plugin In MusicBee If you successfully completed the previous tasks. Then you should find the plugin in MusicBee. In MusicBee, select "Edit > Preferences" then the Plugin tab. If successful you should be able to see your plugin's name in the list! Final Note That's it! You've setup Visual Studio to copy the your plugin files to MusicBee automatically and run MusicBee so you can debug you're code. All debug features work such as breakpoint, ignoring user exceptions, showing runtime errors and more. In the rest of the tutorial, we'll build a simple interactive form with MusicBee's API. Adding a User Interface This plugin will show basic interaction with MusicBee's API. We are going to create a form that controls MusicBee. Adding A Form The first thing we are going to do is create a form which the user will interact with. Right click on the project file, select Add then Windows Form. Leave the default name "Form1.cs" Add a button & a label to the form. Add the text "State" to both of the controls. (Will change it during runtime) This is the interface the user will see once they click on the menu item to start the plugin. Adding A Menu Item To MusicBee Now that we have the form, the user needs someway of accessing it. The simplest way is adding a new menu item in MusicBee. We'll add a menu item named "Start My Plugin" in the tools menu. This menu item needs to be added when MusicBee initializes our plugin. Open the file "TestCSharpDll.cs" - the same file you set the properties of the plugin, create a the new methods as follows: private void createMenuItem() { } private void menuClicked(object sender, EventArgs args){ } Using the API to create a menu item. We use the "MB_AddMenuItem" method in the API. It has three parameters to call it. MB_AddMenuItem(string menuPath, string hotkeyDescription, EventHandler handler) * The menu path is the location in MusicBee where we want to place our menu button. * hotkeyDescription is so that the user can set a shortcut key to open the menu item * handler is a event handler that is called when our menu item has been called. Add this code to createMenuItem: mbApiInterface.MB_AddMenuItem("mnuTools/Start My Plugin", "HotKey For Start My Plugin", menuClicked); The next step is to add the event handler. This simple code will create a new form instance and show it. Form1 myForm = new Form1(); myForm.Show(); Finally, add the method call in the Initialize method. createMenuItem(); Now run the plugin (Build the solution, start debugging). Make sure MusicBee is closed before rebuilding otherwise you'll get an error. Give the button something to do Alright, so if you've made it this far. The form will show when the user clicks on the button. Now we need to make the button do something. We're going to use the API to pause and play MusicBee depending on it's state. We'll need two API calls here. Player_GetPlayState - Return the Enum: PlayState (Undefined, Loading, Playing, Paused, Stopped) Player_PlayPause - Switches the play state Now we need to add some code to the form, * button1_OnClick() - When the button is pressed * private string getPlayerState() - Get the current play state * Constructor: public Form1(Plugin.MusicBeeApiInterface pApi) - Sets the current state to the label & button * Member Variable: private Plugin.MusicBeeApiInterface mApi - Stored so we can call the API in other methods Other Simple MusicBee API Interactions Section TODO Working with Notifications from MusicBee Category:Guides Category:Plugins